Release 10.1A: OpenEdge Development:
Progress 4GL Reference

BUFFER-COPY( ) method

This method copies any common fields, determined by name, data type, and extent-matching, from the source buffer to the receiving buffer. If there are fields in one buffer that do not exist in the other, they are ignored. This method is used to accommodate temp-tables of joins.

Return type: LOGICAL

Applies to: Buffer object handle

Syntax

BUFFER-COPY( source-buffer-handle    [ , except-list [ , pairs-list [ , no-lobs ] ] ] )

source-buffer-handle

An expression that evaluates to the source buffer handle.

except-list

A character expression that evaluates to a comma-separated list of field names to be excluded from the copy.

pairs-list

A character expression that evaluates to a comma-separated list of field-name pairs to be copied.

You can also specify an array element as one or both of the fields. This lets you copy a field or array element from one buffer to a field or array element in the other buffer, when the two fields do not have the same name. The order within each field-name pair does not matter; each pair must contain one field name from the source and one field name from the target.

You can also copy one entire array to another by specifying its name without a subscript.

no-lobs

A logical expression indicating whether to ignore BLOB and CLOB fields in the copy. If TRUE, BLOB and CLOB fields are ignored during the copy. If FALSE, BLOB and CLOB fields are copied along with the other fields. The default value is FALSE (that is, BLOB and CLOB fields are included in the copy).

The following example fragment copies the customer table to the buffer, bh, except that customer.sales-rep is copied to a field called cust-sales-rep in the buffer:

bh:BUFFER-COPY(buffer customer:handle,?,"cust-sales-rep,sales-rep").

Note

When copying buffers in a ProDataSet object, Progress checks as to whether the BUFFER-COPY( ) method satisfies the following two requirements:
The copy is between a buffer on a Data-source object table and the corresponding ProDataSet temp-table buffer. This means the operation can use any buffer for the data source database table, but only the default buffer for the ProDataSet temp-table.
There are no except-list or pairs-list arguments for the BUFFER-COPY( ) method.

If these two requirements are satisfied, the BUFFER-COPY( ) method identifies the fields to copy based on the pairs-list argument specified in the ATTACH-DATA-SOURCE( ) method for the Data-source object, if any, along with either the except-list or include-list arguments, if any. Because the ATTACH-DATA-SOURCE( ) method already allows you to define a field mapping between a Data-source object buffer and a ProDataSet temp-table buffer, as well as a list of fields to include or exclude from the operation, you do not need to specify these in the BUFFER-COPY( ) method.

When copying records that contain a BLOB or CLOB field, Progress copies the object data associated with the source record to the target record. If the BLOB or CLOB field in the source record contains the Unknown value (?), Progress stores the Unknown value (?) in the BLOB or CLOB field of the target record. If the target record already has object data associated with it, Progress deletes that object data before copying the new object data.
Use the no-lobs option with the BUFFER-COPY( ) method to ignore large object data when copying records that contain BLOB or CLOB fields. More specifically:
When you copy a source record to a new target record, Progress sets the value of the BLOB or CLOB field in the target record to the Unknown value (?).
When you copy a source record to an existing target record, Progress does not change the value of the BLOB or CLOB field in the existing target record.

You can also use the except-list option to exclude BLOB and CLOB fields from the copy.